# Environment API

Here you can find all the environment related APIs.

> See [Multi-Environment Builds](/guide/advanced/environments) for more details.

## Environment Context

Environment context is a read-only object that provides some context information about the current environment.

In Rsbuild's [Plugin hooks](/plugins/dev/hooks#plugin-hooks), you can get the environment context object through the `environment` or `environments` parameter.

```ts
type EnvironmentContext = {
  name: string;
  browserslist: string[];
  config: NormalizedEnvironmentConfig;
  distPath: string;
  entry: RsbuildEntry;
  htmlPaths: Record<string, string>;
  tsconfigPath?: string;
};
```

### name

The unique name of the current environment is used to distinguish and locate the environment, corresponds to the key in the [environments](/config/environments) configuration.

- **Type:** `string`
- **Example:**

```js
api.modifyRspackConfig((config, { environment }) => {
  if (environment.name === 'node') {
    // modify config for node environment
  }
  return config;
});
```

### browserslist

The browserslist configuration of the current environment. See [Browserslist](/guide/advanced/browserslist) for more details.

- **Type:** `string[]`
- **Example:**

```js
api.modifyRspackConfig((config, { environment }) => {
  console.log(environment.browserslist);
  return config;
});
```

### config

The normalized Rsbuild config for the current environment.

- **Type:**

```ts
type NormalizedEnvironmentConfig = DeepReadonly<{
  dev: NormalizedDevConfig;
  html: NormalizedHtmlConfig;
  tools: NormalizedToolsConfig;
  source: NormalizedSourceConfig;
  server: NormalizedServerConfig;
  output: NormalizedOutputConfig;
  plugins?: RsbuildPlugins;
  security: NormalizedSecurityConfig;
  performance: NormalizedPerformanceConfig;
  moduleFederation?: ModuleFederationConfig;
}>;
```

- **Example:**

```js
api.modifyRspackConfig((config, { environment }) => {
  // Rspack config
  console.log(config);
  // Rsbuild config for current environment
  console.log(environment.config);
  return config;
});
```

### distPath

The absolute path of the output directory, corresponding to the [output.distPath.root](/config/output/dist-path) config in `RsbuildConfig`.

- **Type:** `string`

```js
api.modifyRspackConfig((config, { environment }) => {
  console.log(environment.distPath);
  return config;
});
```

### entry

The entry object from the [source.entry](/config/source/entry) option.

- **Type:**

```ts
type RsbuildEntry = Record<string, string | string[] | EntryDescription>;
```

- **Example:**

```js
api.modifyRspackConfig((config, { environment }) => {
  console.log(environment.entry);
  return config;
});
```

### htmlPaths

The path information for all HTML assets.

This API will return an object, the key is the entry name and the value is the relative path of the HTML file in the dist directory.

- **Type:**

```ts
type htmlPaths = Record<string, string>;
```

- **Example:**

```js
api.modifyRspackConfig((config, { environment }) => {
  console.log(environment.htmlPaths);
  return config;
});
```

### tsconfigPath

The absolute path of the tsconfig.json file, or `undefined` if the tsconfig.json file does not exist in current project.

- **Type:**

```ts
type TsconfigPath = string | undefined;
```

- **Example:**

```js
api.modifyRspackConfig((config, { environment }) => {
  console.log(environment.tsconfigPath);
  return config;
});
```

## Environment API

Environment API provides some APIs related to the multi-environment build.

You can use environment API via [rsbuild.createDevServer()](/api/javascript-api/instance#rsbuildcreatedevserver) or [dev.setupMiddlewares](/config/dev/setup-middlewares), which allows you to get the build outputs information for a specific environment in the server side.

```ts
type EnvironmentAPI = {
  [name: string]: {
    getStats: () => Promise<Stats>;
    loadBundle: <T = unknown>(entryName: string) => Promise<T>;
    getTransformedHtml: (entryName: string) => Promise<string>;
  };
};
```

### getStats

Get the build stats of current environment.

- **Type:**

```ts
type GetStats = () => Promise<Stats>;
```

- **Example:**

```ts
const webStats = await environments.web.getStats();

console.log(webStats.toJson({ all: false }));
```

### loadBundle

Load and execute the bundles on the server side. This method returns the exports of the entry module.

- **Type:**

```ts
/**
 * @param entryName - Entry name, corresponding to a key in Rsbuild `source.entry`
 * @returns The return value of the entry module
 */
type LoadBundle = <T = unknown>(entryName: string) => Promise<T>;
```

- **Example:**

```ts
// Load the bundle of `main` entry
const result = await environments.node.loadBundle('main');
```

### getTransformedHtml

Get the HTML template content after compilation and transformation.

- **Type:**

```ts
type GetTransformedHtml = (entryName: string) => Promise<string>;
```

- **Example:**

```ts
// Get the HTML content of main entry
const html = await environments.web.getTransformedHtml('main');
```

This method returns the complete HTML string, including all resources and content injected through HTML plugins.
